home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d13 / probe20.arc / PROBE.DOC < prev    next >
Encoding:
Text File  |  1990-04-18  |  8.0 KB  |  238 lines
  1.                 PROBE
  2.                 =====
  3.  
  4.                   By
  5.               Colin J. Stearman
  6.                  [71036,256]
  7.  
  8. PURPOSE
  9.  
  10.     To analyze the performance of a program to determine where
  11. optimization will be of the most benefit.
  12.  
  13. FEATURES
  14.  
  15.     * Samples user program every 55 milli-seconds(using the DOS timer)
  16.     * Monitors routine currently being executed
  17.     * Displays results to screen or file
  18.     * Displays results by address and by decending use frequency
  19.     * Works with all memory model types
  20.     * Independent of source language type
  21.     * Allows user to specifically exclude counting any modules
  22.     * User settable timer interrupt number
  23.  
  24. OPERATION
  25.  
  26.     PROBE is invoked with the following command:
  27.  
  28.     PROBE [/I:n] PROG_NAME.[EXE|COM] PROG_ARG1 ... PROG_ARGn
  29.  
  30. The optional /I:n argument allows the user to select the interrupt
  31. number for the sample timer. 'n' is in hexadecimal. On normal DOS/IBM
  32. machines this will be 8. If you do not understand this argument leave
  33. it out. It is provided to allow non-standard machines to select other
  34. interrupt numbers for the sample timer. Whenever the PC activates
  35. this interrupt the program being probed is sampled to find out which
  36. routine it is in. The more frequent the interrupts the greater the
  37. sample number and the better the results.
  38.  
  39. It is essential that the program to be probed be given with its full
  40. extension. Any arguments it requires can then follow. The simplest
  41. form of command line is:
  42.  
  43.     PROBE PRTEST.EXE
  44.  
  45. This will analyze PRTEST.EXE which does not require any arguments. This
  46. happens to be a test program included with this package.
  47.  
  48.     PROBE must have available to it the following files in the default
  49. directory:
  50.  
  51.     COMLOAD.COM
  52.     EXELOAD.EXE
  53.     progname.MAP
  54.  
  55. An exclusion file may also be optionally available to PROBE and must
  56. have the name:
  57.  
  58.     progname.EXC
  59.  
  60.  
  61.     The first 2 programs are used to determine where DOS will
  62. load the program to be probed. The last is a map file created by the
  63. Microsoft linker LINK when it linked the programto be probed. The
  64. "/m" switch must be used when linking the program to provide a full
  65. map of the program. For example, the PRTEST program was linked with:
  66.  
  67.     LINK PRTEST/m;
  68.  
  69.     As PROBE runs, it first determines where the user program will be
  70. loaded and reports this to the user. Then it asks for the destination
  71. of the resulting data. This can be a file or the CRT screen. If a filename
  72. is provided with no extension, .PRB is automatically added.
  73.  
  74.     PROBE then reads the program MAP file and stores the data on the
  75. program modules.  It then looks for an exclusion file containing
  76. module names to be excluded from the analysis. The file name must
  77. have the same name as the program and map file, but with an extension
  78. of .EXC. The format of this file is:
  79.  
  80. ;  This is a module exclusion list for PROBE
  81. module_name1      any comment
  82.  
  83. module_name2
  84. module_name3
  85. ; end of exclusion file
  86.  
  87.     The module name must be the first word on the line but may have
  88. leading spaces. The case must be exactly as it appears on the MAP
  89. file. Blank lines are ignored, as are lines starting with a
  90. semicolon, thus allowing comment lines.
  91.  
  92.     If no exclusion file is found, the PROBE announces this and
  93. proceeds normally.
  94.  
  95.     PROBE then runs the user program and passes it any supplied arguments.
  96. As the program runs, PROBE is activated by the system clock and a
  97. note is made every 55mS of the routine or module currently being executed.
  98.  
  99.     When the user program terminates, the PROBE results are written to
  100. the chosen output. First a table of results is generated in address
  101. order and then another table in decreasing count frequency order.
  102.  
  103.     One temporary file is created by PROBE. It is name "REGISTER"
  104. and is deleted when PROBE terminates normally. Also various
  105. self-expanatory error message may be issued during abnormal PROBE
  106. operation.
  107.  
  108.  
  109. ANALYZING RESULTS
  110.  
  111.     The routines or modules at the top of the second table are
  112. there because PROBE found them active more frequently then those
  113. below them.  This suggests that improving their efficiency will have
  114. the most effect on overall program performance.
  115.  
  116.     Beware of input/output routines when analyzing results. If
  117. the program waits for user input, PROBE will obviously find the
  118. program frequently in the associated routines. Thus these results can
  119. be misleading.  Routines which deliberately waste time should also be
  120. indentified when analyzing results. Such modules as these can be
  121. included in the optional EXCLUSION FILE so that they are not
  122. considered during the analysis.
  123.  
  124. EXAMPLE PROGRAM
  125.  
  126.     The program PRTEST supplied in this package was used to test
  127. PROBE. It is written in C and calls 5 routines each which "waste"
  128. twice as much time as the previous. A sixth routine is included (but
  129. never called) to check for bugs in identifying probed routines.
  130.  
  131. The typical results from the command:
  132.  
  133.     PROBE PRTEST.EXE
  134.  
  135. are:
  136.  
  137. PROBE Program Performance Analyzer    V2.00
  138.       Written by Colin Stearman [71036,256]
  139.  
  140. PROBE: Reading program map file . . .
  141. PROBE: Map symbol count: 117
  142. PROBE: Map table size: 1053 bytes
  143. PROBE: Symbols processed: 000117
  144. PROBE: Probe of program PRTEST.EXE
  145. PROBE: Program's base code segment is 696A
  146. PROBE: Enter results filename [.PRB] (<ENTER> for screen)? 
  147. PROBE: Executing PRTEST.EXE . . .
  148. ============================================================
  149.  
  150. test1                (these lines output by PRTEST)
  151. test2                (  "     "      "   "     "  )
  152. test3                (  "     "      "   "     "  )
  153. test4                (  "     "      "   "     "  )
  154. test5                (  "     "      "   "     "  )
  155.  
  156. ============================================================
  157.  
  158. PROBE: PRTEST.EXE terminated(0)
  159.  
  160. PRTEST.EXE           Page 1         04-18-1990   11:45:00pm
  161.  
  162.         PROBE results by SYMBOL ADDRESS
  163.  
  164.   ADDRESS  |             SYMBOL                | COUNT
  165. ===========|===================================|========
  166. 0000:0058  |  _test1                           |      14 
  167. 0000:0084  |  _test2                           |      28 (Excluded)
  168. 0000:00B0  |  _test3                           |      43 
  169. 0000:00DC  |  _test4                           |      56 
  170. 0000:0108  |  _test5                           |      70 (Excluded)
  171. ========================================================
  172.  
  173.  
  174. PRTEST.EXE           Page 2         04-18-1990   11:45:00pm
  175.  
  176.         PROBE results by COUNT
  177.  
  178.   COUNT    |             SYMBOL                |PERCENT
  179. ===========|===================================|========
  180.       56   |  _test4                           |  49.56%
  181.       43   |  _test3                           |  38.05%
  182.       14   |  _test1                           |  12.39%
  183. ========================================================
  184.  
  185.  
  186. End of PROBE analysis report
  187.  
  188. As expected, the second report indicates that most time was spent in
  189. "_test5" with decreasing amounts through to "_test1".  As "_test6"
  190. was not called it does not appear.
  191.  
  192. CONCLUSION
  193.  
  194.     You should have the following files in the ZIP file:
  195.  
  196.             PROBE.EXE   
  197.             COMLOAD.COM 
  198.             EXELOAD.EXE 
  199.             PRTEST.EXC  
  200.             PRTEST.MAP  
  201.             PRTEST.EXE  
  202.             PROBE.PRB   
  203.             PRTEST.C    
  204.             PROBE.DOC   
  205.             
  206.             
  207. If you find this program useful I would be pleased to hear from you. Leave
  208. me some EMAIL. Any comments on improvements or changes would be
  209. welcome.
  210.  
  211. ACKNOWLEDGEMENTS
  212.  
  213.     PROBE is based on a program I found on CompuServe called
  214. PROFILE. I do not know the name of the author but wish to acknowledge
  215. his efforts.
  216.  
  217. COLIN STEARMAN [71036,256]
  218.  
  219.                 ====*****====
  220.  
  221. Version 2.00 Changes.
  222.  
  223. 1. Memory usage has been improved so that approximately 10 times as 
  224.    many function identifiers can be processed from the MAP file. Memory
  225.    usage for the identifier table is now displayed.
  226.  
  227. 2. The <exclude> feature has been modified. The calls to excluded
  228.    functions are now counted but not included in the second report or in
  229.    the percentage calculation for the second report. The first report
  230.    shows those functions being excluded.
  231.  
  232. 3. A bug has been fixed which caused incorrect results to be
  233.    returned when programs had a large number of function identifiers.
  234.  
  235. 4. COMLOAD.COM has been rewritten to make it smaller.
  236.  
  237.                 ====*****====
  238.